package com.pokermind.model.example;

import com.pokermind.model.enums.ErrorCode;
import com.pokermind.model.exception.PokerBusinessException;

/**
 * 错误码使用示例
 * 展示如何正确使用ErrorCode枚举和异常类
 * 
 * @author PokerMind Team
 */
public class ErrorCodeUsageExample {
    
    /**
     * 演示手牌不存在异常
     */
    public void demonstrateHandNotFound() {
        Long handId = 12345L;
        
        // 标准错误响应格式示例
        /*
        {
          "success": false,
          "data": null,
          "error": {
            "code": "HAND_NOT_FOUND",
            "message": "指定的手牌记录不存在",
            "details": {
              "field": "hand_record_id",
              "value": "12345",
              "constraint": "must_exist_in_database"
            }
          },
          "meta": {
            "timestamp": "2025-08-09T10:30:00.000Z",
            "request_id": "req_1234567890abcdef"
          }
        }
        */
        
        throw new PokerBusinessException.HandNotFoundException(handId);
    }
    
    /**
     * 演示行动金额无效异常
     */
    public void demonstrateInvalidActionAmount() {
        String actionType = "raise";
        String amount = "50.00";
        String constraint = "must_be_at_least_200.00";
        
        // HTTP状态码: 422 (UNPROCESSABLE_ENTITY)
        // 错误码: ACTION_INVALID_AMOUNT
        throw new PokerBusinessException.InvalidAmountException(actionType, amount, constraint);
    }
    
    /**
     * 演示AI服务不可用异常
     */
    public void demonstrateAIServiceUnavailable() {
        String reason = "AI analysis service is temporarily down for maintenance";
        
        // HTTP状态码: 503 (SERVICE_UNAVAILABLE)
        // 错误码: AI_SERVICE_UNAVAILABLE
        throw new PokerBusinessException.AIServiceUnavailableException(reason);
    }
    
    /**
     * 演示认证Token过期异常
     */
    public void demonstrateTokenExpired() {
        // HTTP状态码: 401 (UNAUTHORIZED)
        // 错误码: AUTH_TOKEN_EXPIRED
        throw new PokerBusinessException.TokenExpiredException();
    }
    
    /**
     * 演示如何检查错误码
     */
    public void demonstrateErrorCodeChecking() {
        try {
            // 某些业务操作
            demonstrateHandNotFound();
        } catch (PokerBusinessException ex) {
            ErrorCode errorCode = ex.getErrorCode();
            
            switch (errorCode) {
                case HAND_NOT_FOUND:
                    System.out.println("处理手牌不存在的情况");
                    break;
                case ACTION_INVALID_AMOUNT:
                    System.out.println("处理行动金额无效的情况");
                    break;
                case AI_SERVICE_UNAVAILABLE:
                    System.out.println("处理AI服务不可用的情况");
                    break;
                default:
                    System.out.println("处理其他业务异常: " + errorCode.getCode());
                    break;
            }
            
            // 获取HTTP状态码
            System.out.println("HTTP Status: " + errorCode.getHttpStatus());
            
            // 获取标准化消息
            System.out.println("Error Message: " + errorCode.getMessage());
            
            // 获取详细信息
            System.out.println("Details: " + ex.getDetails());
        }
    }
    
    /**
     * 演示通用业务异常使用
     */
    public void demonstrateGenericBusinessException() {
        // 直接使用ErrorCode枚举
        throw new PokerBusinessException(ErrorCode.HAND_INVALID_STATE, 
                                       "current_state: active, required_state: completed");
    }
}

/*
按照API文档6.2节，完整的业务错误码映射表：

手牌管理错误 (HAND_*) - HTTP状态码
┌────────────────────────────────┬──────┬─────────────────────────────────┐
│ 错误码                          │ 状态码│ 描述                            │
├────────────────────────────────┼──────┼─────────────────────────────────┤
│ HAND_NOT_FOUND                 │ 404  │ 指定的手牌记录不存在             │
│ HAND_ALREADY_EXISTS            │ 409  │ 手牌ID重复                      │
│ HAND_ALREADY_COMPLETED         │ 409  │ 手牌已结束                      │
│ HAND_INVALID_STATE             │ 422  │ 手牌状态无效                    │
│ HAND_INVALID_STREET_TRANSITION │ 422  │ 街道转换无效                    │
│ HAND_BOARD_CARDS_MISMATCH      │ 422  │ 公共牌不匹配                    │
└────────────────────────────────┴──────┴─────────────────────────────────┘

玩家和座位错误 (PLAYER_*) - HTTP状态码
┌────────────────────────────────┬──────┬─────────────────────────────────┐
│ PLAYER_SEAT_OCCUPIED           │ 409  │ 座位已被占用                    │
│ PLAYER_NOT_FOUND               │ 404  │ 玩家不存在                      │
│ PLAYER_MULTIPLE_HERO           │ 422  │ 多个Hero玩家                    │
│ PLAYER_INSUFFICIENT_PLAYERS    │ 422  │ 玩家数不足                      │
│ PLAYER_INVALID_STACK           │ 422  │ 筹码数无效                      │
└────────────────────────────────┴──────┴─────────────────────────────────┘

行动验证错误 (ACTION_*) - HTTP状态码  
┌────────────────────────────────┬──────┬─────────────────────────────────┐
│ ACTION_INVALID_SEAT            │ 422  │ 无效座位号                      │
│ ACTION_WRONG_TURN              │ 422  │ 不是该玩家回合                  │
│ ACTION_INVALID_AMOUNT          │ 422  │ 行动金额无效                    │
│ ACTION_INSUFFICIENT_STACK      │ 422  │ 筹码不足                        │
│ ACTION_INVALID_TYPE            │ 422  │ 行动类型无效                    │
│ ACTION_MIN_RAISE_VIOLATION     │ 422  │ 违反最小加注规则                │
│ ACTION_PLAYER_NOT_ACTIVE       │ 422  │ 玩家非活跃状态                  │
└────────────────────────────────┴──────┴─────────────────────────────────┘

AI服务错误 (AI_*) - HTTP状态码
┌────────────────────────────────┬──────┬─────────────────────────────────┐
│ AI_SERVICE_UNAVAILABLE         │ 503  │ AI服务不可用                    │
│ AI_ANALYSIS_TIMEOUT            │ 504  │ 分析超时                        │
│ AI_INSUFFICIENT_DATA           │ 422  │ 数据不足以分析                  │
│ AI_INVALID_PARAMETERS          │ 422  │ 分析参数无效                    │
│ AI_QUOTA_EXCEEDED              │ 429  │ AI分析配额超限                  │
└────────────────────────────────┴──────┴─────────────────────────────────┘

认证和权限错误 (AUTH_*) - HTTP状态码
┌────────────────────────────────┬──────┬─────────────────────────────────┐
│ AUTH_TOKEN_INVALID             │ 401  │ Token无效                       │
│ AUTH_TOKEN_EXPIRED             │ 401  │ Token已过期                     │
│ AUTH_INSUFFICIENT_SCOPE        │ 403  │ 权限范围不足                    │
│ AUTH_RATE_LIMITED              │ 429  │ 请求频率超限                    │
└────────────────────────────────┴──────┴─────────────────────────────────┘
*/